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Sir: 

I, the undersigned, Yoram Tsarfati, hereby declare as 
follows : 

1) I am the Applicant in the patent application identified 
above, and am the inventor of the subject matter described and 
claimed in claims 1-48 therein. 

2) Prior to May 18, 2001, I reduced my invention to 
practice, as described and claimed in the subject application, 
in Israel, a WTO country. I implemented the invention in the 
form of software code, which runs on an embedded CPU in a 
generic communication line card produced by my employer, 
Corrigent Systems. The code comprised a number of generic 
application handler modules, which were designed to be used by 
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programmers in creating proprietary handlers for new line 
cards as needed. 

3) As evidence of the reduction to practice of the present 
invention, I attach hereto a number of programmer guides / 
which were prepared by software programmers in our company to 
describe our generic application handler modules and instruct 
other programmers in creating proprietary handlers using these 
modules. The following documents are attached: 

• Exhibit A: Generic Performance Monitoring 
Handler. 

• Exhibit B: Generic Configuration Handler. 

• Exhibit C: Generic Maintenance Handler. 

• Exhibit D: Generic Alarm Handler. 

• Exhibit E: A report generated by ClearCase, a 
tool we use to manage and organize software 
versions, showing logging of the documents 
presented above in Exhibits A-D. The dates that 
are blacked out in this Exhibit are prior to May 
18, 2001. 



4) The following table shows the correspondence between 
the elements of the method claims in the present patent 
application and elements of the material in the exhibits: 



Claim 1 


Exhibits A-D 


1 . A method for producing 
embedded software, 
comprising : 


Exhibit A-D contain 
instructions on programming a 
processor that is embedded in a 
generic line card. 
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providing one or more 
generic application handler 
programs, each such program 
comprising computer program 
code for performing generic 
application functions common 
to multiple types of hardware 
modules used in a 
communication system; 


Section 3.2 on page 5 of 
Exhibit A describes the 
performance monitoring (PM) 
generic part. Similar generic 
parts are described in Exhibits 
B-D. Monitoring, configuration 
and maintenance functions are 
common to nearly all types of 
hardware modules that are used 
in communication systems. 


generating specific 
application handler code to 
associate the generic 
application functions with 
specific functions of a 
device driver for at least 
one of the types of the 
hardware modules; and 


Section 3.3 on page 5 of 
Exhibit A describes the API 
that is provided as a base for 
the programmer to develop a 
proprietary handler. The 
architecture, including the 
device driver, is shown in the 
figure on this page. Section 
4.3.2 on pages 9-10 gives 
details of the API. 


compiling the generic 
application handler programs 
together with the specific 
application handler code to 
produce machine -readable code 
to be executed by an embedded 
processor in the at least one 
of the types of the hardware 
modules . 


Section 4.4. on pages 10-11 of 
Exhibit A lists source and 
header files. It is inherently 
clear that in order for the 
program to run on the 
processor, these files must be 
compiled. 
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Claim 2 




2 . A method according to 
claim 1, wherein providing 
the generic application 
handler programs comprises 

X. ^ V J. J. 1 IM CllX kJ _L X w CI ^ ^ i 

program interface (API) to 
enable a system management 
program in the communication 
system to invoke the generic 
application functions. 


Section 2 on page 4 of Exhibit 
A states that the PM handler 
provides an API to other 
handlers (which may include the 


Claim 3 




3 . A method according to 
claim 2, wherein the one or 
more generic application 
handler programs comprise a 
plurality of generic 
application programs, and 
wherein providing the API 
comorises enablinQ one of the 
generic application programs 
to invoke the generic 
application functions of 
another of the generic 
application programs. 


See section 2, page 4, of 
Exhibit A, as noted in 
reference to claim 2 . 
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Claim 4 




4 . A method according to 
claim 1, wherein providing 
the generic application 
handler programs comprises 
providing a performance 

[IIOIIX L.L;X Xll^ IlCtilUJ.CIl. / ±XX^ J. LIUXXJ.^ 

a performance monitoring 
function for counting 
selected events relating to 
performance of the hardware 
modules . 


Exhibit A describes a 
performance monitoring handler. 
Event counters are listed in 
the first table in section 
4.2.1. 


Claim 5 




5 . A method according to 
claim 4, wherein generating 
the specific application 
handler code comprises 
sDecifvina a reaister in one 
of the types of the hardware 
modules whose contents are to 
be passed to the performance 
monitoring function for 
counting . 


Section 4.3 on page 8 of 
Exhibit A describes an API to 
other handlers, which includes 
counter and collection 
functions for use in collecting 
register contents from other 
modules . 
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Claim 6 




6 . A method according to 
claim 4, wherein providing 
the generic application 
handler programs further 
comprises providing an alarm 
handler, and wherein 
providing the performance 
monitoring handler comprises 
providing a programmable 
performance threshold and an 
alarm invocation function, 

Qiioh t'Vi^t" wVif^n a p'oiint" o"F ^Vi^ 
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selected events exceeds the 
threshold, the performance 
monitoring handler sends an 

alarm message to the alarm 
handler. 


The first table on page 7 
(section 4.2.1) of Exhibit A 
shows alarm counters and 
thresholds . 


Claim 7 




7 . A method according to 
claim 1, wherein providing 
the generic application 
handler Droarams comprises 
providing a maintenance 
handler, including a testing 
function for detecting 
failures in the hardware 
modules . 


Exhibit C describes the 
maintenance handler. Testing 
functions are described in 
section 4 . 1 on oaoe 7 . 

\ 
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Claim 8 




8 . A method according to 
claim 7, wherein generating 
the specific application 
handler code comprises 
associatina the testina 
function with at least one of 
a self test and a sanity test 
of a component in the at 
least one of the types of the 
hardware modules. 


Self test and sanity test 
functions are listed in section 
4.2.1 on page 7 of Exhibit C. 


Claim 9 




9, A method according to 
claim 7, wherein providing 
the generic application 
handler programs further 
comprises providing an alarm 
handler, and wherein 
providing the maintenance 
handler comprises providing 
an alarm invocation function, 
such that when one of the 
failures is detected, the 
maintenance handler sends an 
alarm message to the alarm 
handler. 


Alarm triggering is described 
in the second paragraph of 
section 4 . 1 on page 7 of 
Exhibit C. 
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Claim 10 




10. A method according to 
claim 1, wherein providing 
the generic application 
handler programs comprises 

'n'm\7"i r\ i no ^ r'OTi "F "i en i t^;^ t" *i on 

handler, for holding 
configuration and state 
information regarding 
components of the hardware 
modules . 


Exhibit B describes the 
configuration handler. 
Functions of this handler are 
described in section 2 on page 


claim 11 




11. A method according to 
claim 1, wherein providing 
the generic application 
handler programs comprises 
providing an alarm handler, 
including functions for 
receiving and responding to 
alarm messages generated by 
others of the application 
handler programs. 


Exhibit D describes the alarm 
handler. The flow of alarm 
messages from other handlers is 
shown in the figure on page 8. 
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Claim 12 




12 . A method according to 
claim 11, wherein providing 
the alarm handler comprises 
providing a programmable 
prioritization function, for 
determining an order of 
priority for processing of 
the alarm messages by the 
alarm handler. 


A table for setting alarm 
priorities is shown at the top 
of page 12 in section 4.4 of 
Exhibit D. 


Claim 13 




13 . A method according to 
claim 11, wherein generating 
the specific application 
handler code comprises 
specifying a component in one 
of the types of the hardware 
modules to actuate so as to 
notify a user of the system 
of the alarm message. 


Actuation of different system 
functions in response to alarms 
is described in the third 
paragraph of section 4.4, on 
page 11 of Exhibit D, 
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Claim 14 




14 . A method according to 
claim 11, wherein generating 
the specific application 
handler code further 
comprises specifying one of 

functions of another of the 
generic application handler 
programs to invoke in 
response to the alarm 
message . 


Section 4.3.1 on page 9 of 
Exhibit D describes an API 
between the alarm handler and 
other handlers, which may be 
used to invoke responses to 


Claim 15 




15. A method according to 
claim 11, wherein responding 
to the alarm messages 
comprises sending a 
notification of the alarm 
message from the alarm 
handler to a system 
management program. 


Section 2 on page 5 of Exhibit 
D states that the alarm handler 
notifies the NMS (a system 
management program) by sending 
a trap when an alarm occurs. 
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Claim 16 




16. A method according to 
claim 1, wherein generating 
the specific application 
handler code comprises 
defining specific elements to 
be handled by the generic 
application functions for the 
at least one of the types of 
the hardware modules, and 
registering one of the 
specific functions of the 
device driver for use in 
handing each of the defined 
specific elements. 


Section 4.3.2 on page 9 of 
Exhibit A describes an API that 
may be used to designate the 
specific actions to be 
performed by the proprietary 
part of the handler. 



5) Claims 17-48 recite apparatus and a computer software 
product, with limitations similar to those of method claims 1- 
16. Based on the similarity of subject matter between the 
method, apparatus and software claims, it can similarly be 
demonstrated that we conceived the entire invention recited in 
claims 17-48 prior to May 18, 2001. 

I hereby declare that all statements made herein of my own 
knowledge are true and that all statements made on information 
and conjecture are thought to be true; and further that these 
statements were made with the knowledge that willful false 
statements and the like so made are punishable by fine or 
imprisonment, or both, under Section 1001 of Title 18 of the 
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United States Code and that such willful false statements may 
jeopardize the validity of the application of any patent 
issued thereon. 



Yoram Tsarfati, Citizen of 
Israel 

79 Beit Hanania 
Hof Hacarmel 37807 
Israel 

Date : 
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DATE 

DATE 
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DISTRIBUTION LIST: 



CORRIGENT CONFIDENTIAL AND PROPRIETARY DATA 



Generic PM Handler Software Design for generic line card 
Revision 1.0 



Page 1 




orrige.nt 



s y s T C-.M s 



History Change: 



Rev. 


Date 


Change Description 


Author 

























































Generic PM Handler Software Design for generic line card 
Revision 1.0 



Page 2 



^^Corrigent 

Table of contents 

1. Document Overview 4 

2. Module Overview 4 

3. Module Architecture 4 

3.1 DataBase and DB API 4 

3 .2 PM Generic Mechanism and PM API 5 

3 .3 Proprietary API 5 

4. Module Implementation 6 

4.1. Control flow 6 

4.2. DB & Data structures 6 

4.2.1. Data structures 6 

4.2.2. Databases 7 

4.3. API 8 

4.3.1. API to other handlers 8 

4.3.2. API between the generic and the proprietary parts 9 

4.4. Detailed implementation 10 

4.4.1. Source Files 10 

4.4.2. Header Files 1 1 

5. How to start 11 

5.1. Define the Interval Data 11 

5.2. Implement the Update function 1 1 

6. Module Integration 11 



Generic PM Handler Software Design for generic line card 
Revision 1.0 



Page 3 



orrigent 



I SYSTEMS 



1. Document Overview 

This document mainly contain two parts. One to describe the architecture and 
implementation of the generic Performance Monitoring handler. The second, a 
manual how to use the generic handler to build a proprietary Performance 
Monitoring handler. 

For a programmer that is itching to start his proprietary handler is recommended 
to read section 2 & 3 before jumping to section 5. Section 3 describe in more 
details the implementation of the generic handler. 



2, Module Overview 

This Handler provides a mechanism to maintain a user defined Performance 
Monitoring data base, update it periodically and allow data retrieval from it. It 
also provides an API to other h£indlers. The generic mechanism uses application 
functions (provided by the programmer of the proprietary handler) which allow 
data retrieval from the HW and data base update. 

The PM mechanism periodically updates the data base by reading data from the 
HW. The decision whether an interval is finished can either be done 
independently (after counting a configurable number of seconds) or event driven 
(getting a "close interval" command from another task for example the NMS). 
The working mode should be configured at the beginning and should not be 
changed during the handler's work. 

The PM API allows other handlers to send different commands to the PM such as 
Reset, Start, Close Current Interval, Get/Set collection mode, change the 
collection parameters and more. 

A threshold mechanism is also provided. For each PM counter there is a set of 
thresholds configured by the user. When each threshold is set, an alarm code must 
also be to be sent in case the counter reaches the corresponding threshold. 

3, Module Architecture 

The module is comprised of the follwing components: 

3.1 DataBase and DB API 

The DB creation and handhng is done by this sub-module. It provides an 
API which can only be accessed by the PM Generic Mechanism. It allows 
the creation and handling of the DB in which the PM will be saved. A node 
in the DB contains the interval number, the actual data (which is only 
"understood" by the proprietary part) and a pointer to the next node. 
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3.2 PM Generic Mechanism and PM API 

This is the engine of the whole PM mechanism. It is comprised of a PM 
task, a PM message exchange and a PM timer. The PM timer runs 
periodically. When it expires it sends a message to the PM task with a 
PM_TIMER EXPIRED event. The task waits forever for such a message 
and when it arrives, it performs an update operation. 
This sub-module also includes an API which is exported to all the other 
handlers in order to retrieve PM data and perform actions such as reset or 
start the PM mechanism. 

This sub-module provides the data structure to be saved in the data base (LC 
dependent) and the corresponding threshold structure. 



3.3 Proprietary API. 

This API is provided as a base for the programmer of the proprietary 
handler to complete its implementation. It includes all the Line Card 
dependent functions and configuration parameters. These parameters are 
provided with the most appropriate defaults but must be adjusted by the 
programmer of the proprietary handler. 

This API can be used by the PM Generic Mechanism and by the Data Base. 
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4> Module Implementation 

4.1. Control flow 

The mechanism starts by the call of an initialization function PM_Init(). 
This function creates the PM task, the PM message exchange and the PM 
timer and starts the timer. 

It also calls DB CreateQ API in order to create the PM DB and 
application init function applPMInitQ in order to perform the necessary 
initializations of the proprietary handler. 

Once the PM task, message queue and timer are started, the periodic 
update mechanism is running. Every second (configurable in seconds) the 
timer sends a PM_TIMER_EXPIRED message to the task. The task 
receives this message and calls the generic update function. This function 
calls the application update function which reads data from the different 
HW components and updates it into the DB. The access to the DB is 
performed through the PM Generic Handler. 

If the mechanism is configured to work independently then after 900 
seconds (the number is configurable in seconds) the current PM interval is 
closed. If it is configured to close the interval when an event is sent, then 
only when requested the interval will be closed. The request is done by 
setting the closelnterval flag which is accessed via an API. 
When an update is done each counter is checked to see if one of its 
thresholds has been reached. In case it has, an alarm message is sent to the 
alarm handler, 

4.2. DB & Data structures 



4.2.1. Data structures 







Variable Name»!fWi^'-:'^''" 






EV PM COUNTERO 


Enum type 


Counter type 0 (example) 


EV PM COUNTER! 


Enum type 


Counter type 1 (example) 


EV MAX NUMBER OF COUNTERS 


Enum type 


Max number of counters in the LC 



^ -Interval Bata:S^33PM GOUNTERS^(appl).^ A. ^ 


LVariableName^ 


^Variable Type 


'^Descriptioii^^' , 


TimelnSecs 


CS_UINT16 


Number of elapsed seconds in this 
interval 


PM counter[EV MAX NUMBER OF COUNTERS] 
[MAX_NUM_OF_INTERFACES] 


CS_UINT32 


Two-dimensional array of 
counters: counter type (e.g. CRC) 
X interface number 
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thresh[MAX_NUM_OF_THRESH] 


CS_UINT32 


A number of thresholds for each counter 
(default = 5) 


alann[MAX_NUM_OF_THRESH] 


CS_UINT8 


An alarm to send when each threshold is 
reached 











PM thresh[EV MAX >njMBER OF COUNTERS] 
[MAX NUM OF INTERFACES] 


S_PM__ALARMS 


Thresholds for PM counters 
for each counter type and 
interface number 







^-ffeSt^^iaffiaaiS^aM 


T'^P^aroe^iptioiir'' -4:. w * - 


IntervalNo 


CS UINT8 


Number of interval {0=Current) 


Interval 


S PM COUNTERS 


Interval Data 



4.2.2. Databases 

There are two data bases, two arrays of pointers to functions of the 
proprietary handler and a number of configuration parameters: 

1) The PIVI DB which is an array of intervals of type 
S_PM_INTERV AL pointed to by pm_CurrentInterval at the 
beginning and by pm Lastlnterval at the end. There are 96 
intervals allocated in the array, but the max number of intervals 
used is stored in maxNumOflntervals. The actual number of 
intervals at a given time is stored in numOflntervals. 

2) The PM Thresholds data base PM_Thresh of type 
S_PM_THRESHOLDS. 

3) The following configuration parameters: 















IntervalNumOfSecs 


CS_UINT16 


Number of seconds in one interval 
(default=900) 


PmTimerPeriod 


CS_UINT8 


Length of period in which to update PM (in 
seconds) (default^ 1 ) 


CoUectionMode 


CS_UINT8 


INDEPENDENT or EVENT - whether to close 
an interval independently (according to 
intervalNumOfSecs or event driven 


Closelnterval 


CS_UINT8 


Flag to force the closing of the current interval 
next time the PM is updated 


numOflntervals 


CS UINT8 


Number of intervals currently saved in the DB 


maxNumOflntervals 


CS_UINT8 


Max number of intervals to be saved in the DB 
(configurable by user, and the maximum 
allowed is 96) 
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4,3. API 

4.3.1. API to other handlers 

Syntax: void PM_Imt(void) 
Initialization function 



orrigent 



Syntax: void PM_ResetDB(void) 

Reset the DB - clear the current interval and delete all other 
intervals 



Syntax: void *PM_GetInterval(CS_UINT8 intervalNo) 
Get the data of a specific interval (by its number) 

Syntax: CSJJINT32 PM_GetCounter(CS_UINT8 intervalNo, 

CS_UINT8 counterNo, 
CS^UINTS inter faceNo) 

Get a specific counter 

Syntax: void PM_SetCollectionMode(CS_UINT8 independent_or_event) 
Set the collection mode for updating PM (default = independent) 

Syntax: CS_UINT8 PM_GetCollectionMode(void) 
Get the current collection mode 

Syntax: void PM_UpdateDB (void) 

Peform an update of the PM DB (from HW) 

Syntax: void PM_CloseCurrentInterval(void) 

Set a flag to close the current interval when the (1 sec) period is 
over 

Syntax: void PMJStart(void) 

Start the whole statistics mechanism NOW (reset and if working in 
independent mode start the timer again) 

Syntax: CS_UINT8 PM_ConfigThresholds(CS_UINT8 counterNo, 

CS_UINT8 interfaceNo, 
CS_UINT8 threshNo, 
CS_UINT32 threshValue, 
CS_UINT8 alarmType) 
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Configure thresholds for sending an alarm. Return RC_OK or 
RC_OUT_OF_RANGE 

Syntax: void PM_PrintInterval(CS_UINT8 intervalNo) 
Print an interval of the PM DB 

Syntax: void PM_PrintDB(void) 
Print the complete PM DB 

Syntax: void PM_PrintThresholds(void) 

Print the thresholds of the counters and the alarm to be sent when 
reached 

Syntax: void PM_SetNumOflntervals(CS_UINT8 value) 
Set the number of intervals of the DB 

Syntax: CS_UINT8 PM_GetNumOJIntervals(void) 
Get the number of intervals of the DB 

Syntax: void PM_SetIntervalNumOfSecs(CS_UINT16 value) 
Set the time length of each interval (in seconds) 

Syntax: CS_UINT16 PMJ3etIntervalNumOfSecs(void) 
Get the time length of each interval (in seconds) 



4.3.2. API between the generic and the proprietary parts 

This API allows the generic part to perform actions that are LC 
dependent therefore only the proprietary part can perform them. 

Syntax: void initPMF unctions (void)) 
Init the collection mode (LC specific). 
Also perform some initializations necessary for working. 

Syntax: void applUpdateFromHW( 

S_PM_COUNTERS *IntervalData) 
Collect all the counters from the HW and retum a structure 
containing the new interval data. 

Syntax: void applClearIntervalData( 

S_PM_COUNTERS *IntervalData) 

Clear (set to 0) a given interval 
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Syntax: void applPrintIntervalData( 

S_PM_COUNTERS *pIntervalData) 
Print the data of a specific interval (for debugging) 
When the generic handler is requested to print an interval,it 
calls this function to print the data, which is known only by 
the proprietary handler 



Syntax: void applPrintThresholds(void) 

Print the thresholds for each counter defined in the 
proprietary handler 

Syntax : CSJUINT32 applGetCounter( 

CS_UINT8 counterNOy 
S_PM_COUNTERS pIntervalData, 
CS_UINT8 interfaceNo) 
Get a specific counter value. 

Syntax: void applSetCounter( 

CS_UINT8 counterNoy 
CS_INT8 intervalNoy 
CS_UINT8 interfaceNo, 
CS_UINT32 value) 
Set a specific counter value. 

Syntax: CS_UINT8 applSetThresh ( 

CS_UINT8 counterNOy 
CS_UINT8 InterfaceNOy 
CS_UINT8 threshNoy 
CS_ UINT32 thresh Value, 
CS_UINT8 alarmType) 
Set a threshold value and the corresponding alarm type. 

4.4. Detailed implementation 
4.4.1. Source Files 

This handler is implemented in three modules: 
1. PM_Handler\gen\src\genPM.cpp 

This module contains the implementation of the PM Generic 
Mechanism (task+timer) and all the API exported to the rest of the 
handlers. The init fiinction PM_InitO provided in this module is 
called by the Main Handler. The flow is described in 4. 1 . Control 
flow paragraph. 
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2. PM_Handler\gen\src\genPMDB.cpp 

This module contains the implementation of the PM Data Base and 
provides an API which is known only by the generic handler 



3. PM_Handler\appl\src\PM.cpp 

This module contains the Proprietary API provided to the generic 
mechanism. All actions which are LC dependent are done through 
this API which should be implemented by the programmer of the 
proprietary handler. 

4.4.2. Header Files 

1. exMncVgenPM.h 

Exports PM Generic Mechanism API to all handlers. 



2. PM_Handler\ext_inc\PM.h 

API between the generic and the proprietary handlers. 



3. PM_Handler\gen\inc\inc genPM.h 

PM Generic Mechanism header file 



4. FM__Handler\gen\inc\genPMDB.h 

Data Base API (exported only to the PM Generic Mechanism) 



5. How to start 

In this section it will be described how take the generic handler and turn it into a working 

full PM Handler. 

The steps to do are the following: 

5.1. Define the Interval Data 

Define E_PM_COUNTERS: counter types according to the specific Line Card . 

5.2. Implement the Update function 

updatePMData function: given a counterNo (counter type) and the corresponding 
vector of counters from the DB, get data from HW and update the given vector of 
counters. Function ApplUpdateFromHWQ will call all the update functions. 



6, Module Integration 

This module has interaction with the following handlers: 

• Main Handler : calls function PM InitQ to start the mechanism 

• Alarm Handler: when a threshold is reached by a counter, a message is 
sent to the alarm handler. 

• Configuration Handler: There are a few parameters to configure if needed 
(otherwise they work with a default) described in 4.2.2. Databases. The 
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threshold table should also be configured with values for the thresholds of 
each counter and with the alarm types to send in case a threshold is 
reached. 
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1. Document Overview 

This document mainly contain two parts. One to describe the architecture and 
implementation of the generic configuration handler. The second, a manual how 
to use the generic handler to build a proprietary configuration handler. 
For a programmer that is itching to start his proprietary handler is recommended 
to read section 2 & 3 before jumping to section 5. Section 3 describe in more 
details the implementation of the generic handler. 

2. Module Overview 

This handler provides a known and well defined API for accessing the LC 
configuration. The API provide a get/set function to any field (only get if it was 
defined as read-only) in the configuration DB. The handler interpret the request, if 
it is a get request it return a pointer to the requested field. If it is set request it call 
the user proprietary set function. 

Added to this handler is a generic state machine (it is not part of the 
configuration, it can be ignored if not needed). The machine can get events, and 
move to different states according to the event. When entering or exit state, a user 
proprietary function is called. 
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3, Module Architecture 

The module can be divided into two parts the generic one and the proprietary one. 



Application Handler 



Generic Part 


A N 


Proprietary 
Part 


vj 1/ 



IE 



The generic part will have a well defined API toward other handler, such as the 
MIB handler. The proprieteiry part will be written by the user and will do the 
actual settings to the configuration database. In the proprietary part the user will 
define all the configurable elements that will be managed and will connect his 
fiinctions to the generic part (see more details in section 4.3 & 5). From this 
moment all the calls will be made through the generic handler APIs. 
The generic state machine should be defined by states and events. In the 
proprietary part the user will define all the states and the events of the state 
machine, and will defined a transfer matrix, firom every state what event transfer 
to what state. The states will be connected into proprietary functions that will be 
called upon entering or existing state. 
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4. Module Implementation 

4.1. Control flow 

The handler have a main initialization fiinction CONF_Init, this function 
will initialize the internal handler database. After the initialization it 
require that the user will give for each configurable element a pointer to 
the actual field and a fiinction to set this field. For the state machine the 
user will give the transfer matrix. 

After this initialization the DB can be accessed by calling the API (see 
section 4.3 & 5). The state machine will be driven by sending events to it. 

4.2. DB & Data structures 

The access fiinction to the DB can be divided into get and set fimction. 
The get function return a pointer to the actual data, if it was unable to get 
it, it will return NULL. The set fiinction return RC_OK if the update was 
succeeded or RC FAIL otherwise. 

The send event fiinction for the state machine return void. 
4.2.1. Data structures 



; , " - ST s bo'ard;;sIintem'ace^^ 


S'iGOPaPONENTS , ^ ^\ 


Variable iilme 


VariableJS^pe^..^! 


iDescf iption w . ^ 


pFunc 


void* 


A pointer to the setting function. 


pppValue 


void*** 


A pointer to two-dimensional 
array of pointers to the actual 
data. 


numOfElements 


CS UINT8 


Number of elements 


numOfParamsPer 
Element 


CS_UINT8 


Number of fields per element. 


isReadOnly 


CS BOOL 


The fields are read-only or not 






Variable name 


Variable typSl^'f>*«:"1 


Delcriptidn'^^ ^ r ''^^ f 


stateNum 


E STATES 


The state number 


pEnterFunction 


void* 


A pointer to the entering function 


pEnterFunction 


void* 


A pointer to the exiting function 


moveFunc 


E_STATES 


An array of transfer, for every 
event to which state to move. 



4.2.2. Database 

There are four databases in the system: 

1) boardDB of S_BOARD records. 

2) interfaceDB of S_INTERF ACE records. 

3) componentDB of S_COMPONENT records. 

4) stateMachine of S_STATE records. 
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The size of the databases depends on how many elements are in 
each one. 

4.3. API 

4.3.1. API to other handlers 

There are several APIs that enable other handler (especially the 
MIB handler) to communicate with the handler. 

Syntax: void CONFJnitQ 

This is the main initialization function. It should be called 
once on power-on. 

Syntax: CSJNT8 CONF^SetBoardElement 

(E_BOARD, CS_UINT8, void*, CS_UINT8) 
This function get board element, a field, pointer to a data 
and set the corresponding field to the requested value. The 
setting is done by calling the user proprietary update 
function. The function return RC_OK if the update was 
successfully completed, otherwise RC_FAIL. 

Syntax: CS_INT8 CONF_SetInterfaceElement 

(EJNTERFACE, CS_UINT8, void*, CS^UINTS) 
This function get interface element, a field, pointer to a 
data and set the corresponding field to the requested value. 
The setting is done by calling the user proprietary update 
function. The function return RC_OK if the update was 
successfully completed, otherwise RC_FAIL. 

Syntax: CS_INT8 CONF_SetComponentElement 

(E^COMPONENT, CS_UINT8, void*, CS__UINT8) 
This function get component element, a field, pointer to a 
data and set the corresponding field to the requested value. 
The setting is done by calling the user proprietary update 
function. The function return RC_OK if the update was 
successfully completed, otherwise RC_FAIL. 

Syntax: void* CONF_GetBoardElement 

(E^BOARD, CS_UINT8, CS_UINT8) 
This function get board element, a field and return pointer 
to corresponding field data. The function return NULL if it 
was unable to find the field. 

Syntax: void* CONFjGetlnterfaceElement 

(EJNTERFACE, CS_UINT8, CS_UINT8) 
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This function get interface element, a field and return 
pointer to corresponding field data. The function return 
NULL if it was unable to find the field. 

Syntax: vo/rf* CONFjGetComonentElement 

(E_COMPONENT, CS_UINT8, CS_UINT8) 
This function get component element, a field and return 
pointer to corresponding field data. The fiinction return 
NULL if it was unable to find the field. 

Syntax: void CONFJSendAcHon 
(ENACTIONS) 

This function an event and change the state machine state 
according to it. If the state was actually changed a call is 
made to the exiting and entering functions of the relevant 
states. 

4.3.2. API between the generic and the proprietary parts 

Syntax: voidaddBoard 

(E^BOARD, void*, void**, CS_UINT8, CS_UINT*, CS_BOOL) 
This function get a board element, a pointer to user 
proprietary set function, a pointer to a two-dimensional 
array of pointers to the actual data, number of fields in the 
element, number of elements and does this element is read- 
only. The function update the board DB so when a set 
request is done, it will be connected to the set function, and 
when a get request is done it will be able to retrieve the 
data. 

Syntax: void addlnterface 

(EJNTERFACE, void*, void**, CS^UINTS, CS^UINT*, 
CS_BOOL) 

This function get an interface element, a pointer to user 
proprietary set function, a pointer to a two-dimensional 
array of pointers to the actual data, number of fields in the 
element, number of elements, and does this element is read- 
only. The function update the interface DB so when a set 
request is done, it will be connected to the set function, and 
when a get request is done it will be able to retrieve the 
data. 

Syntax: void addComponent 

(EJCOMPONENT, void*, void**, CSJJINTS, CS_UINT*, 
CSJBOOL) 
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This function get a component element, a pointer to user 
proprietary set function, a pointer to a two-dimensional 
array of pointers to the actual data, number of fields in the 
element, number of elements, and does this element is read- 
only. The function update the component DB so when a set 
request is done, it will be connected to the set function, and 
when a get request is done it will be able to retrieve the 
data. 

Syntax: void setStateMachine 

(E^STATES, void*, void*, E^STATES*, CS_BOOL) 
This function get a state, a pointer to user proprietary 
entering function, a pointer to user proprietary exiting 
function, a pointer to an array of states to move on each 
event and does this state is the initial state. The function 
update the state machine DB so when an event is sent, it 
will know to which state to move and to which function to 
call. 

Syntax: void initBoardFunctionO 

In this function the user should put all his calls to 
addBoard, This function is called by CONF_Init function 
on power-on. 

Syntax: void initlnterfaceFunctionO 

In this function the user should put all his calls to 
addlnterface. This function is called by CONF Init 
function on power-on. 

Syntax: void inltComponentFunctionO 

In this function the user should put all his calls to 
addComponent. This function is called by CONFJnit 
function on power-on. 

Syntax: voidfiUStateMachineO 

In this function the user should put all his calls to 
setStateMachine. This function is called by CONF_Init 
function on power-on. 

Syntax: void initConfProprietaryO 

In this function the user should put all his proprietary 
initializations. This function is called immediately after all 
the generic handler initializations are done by CONFJnit 
function on power-on. 
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4.4. Detailed implementation 

The implementation of this handler is quite simple. We have a common 
header for the generic and the proprietary section toward other handlers, in 
this header the user define all the configurable components in his system 
(see detail explanation in section 5). On the generic section we have four 
databases: boardDB, interfaceDB, componentDB and stateMchine. In the 
proprietary source file {conf.cpp) the user should build his actual DB. We 
provide a skeleton functions for the user to fill, in those function the user 
suppose to connect his proprietary DB and functions to the generic API. 
We provide the user an API to fill the generic handler with a pointers to 
his proprietary DB and functions (see section 5). We also provide a 
skeleton function for general purpose initialization that will be called on 
power-on, if the user need to do some initialization to his data, this is the 
place. On power-on all those skeleton functions will be called by 
CONFJnit. All other handler may perform calls to the user DB using the 
well known API without knowing the real implementation of the user in 
the proprietary section. 



5. How to start 

In this section it will be described how take the generic handler and turn it into a 
working full configuration handler. First we should divide the work into several 
stages: identifying the configurable components, defining the fields per element, 
defining user proprietary set functions and connecting it to the generic handler. 

5.1. Identifying the configurable components 

First we should take a look at our system component and see which of 
them can be configured. Next we should divide them into three categories: 
interfaces, components and board. The interface elements usually will be 
all the connectors to the outside world (Uke a transceiver, framer...). The 
component elements usually will be elements on the LC (like a FPGA, 
SERDES ...)• The board will contain a logical configuration of the LC 
(like type, serial number, functionality...). After knowing that, let the 
handler know about them too. In genConf.h file there is a structure 
E_BOARD that hold all the board elements, add them to there (you must 
keep the element EV_BOARD_LAST at the end of the structure). 
For example let assume we need to configure the CPU, the structure 
should look like this: 

typedef enum 
{ 

EV_BOARD_CPU, 
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EV_BOARD_LAST 
}E_BOARD: 



There is a structure EJNTEFACE that hold all the interface elements, add 
them to there (you must keep the element EVJNTERFACEJAST at the 
end of the structure). 

For example let assume we need to configure the FRAMER, the structure 
should look like this: 



typedef enum 
{ 

EVJNTERFACE_FRAMER. 
EVJNTERFACEJAST 
}EJNTERFACE; 

There is a structure EJJOMPONENTthat hold all the component elements, 
add them to there (you must keep the element EVJOOMPONENTJAST at 
the end of the structure). 

For example let assume we need to configure the FPGA, the structure 
should look like this: 



typedef enum 
{ 

EVJOOMPONENTJ'PGA, 
EVj:OMPONENTJAST 
}Ej:OMPONENT; 



5.2. Defining the fields per element 

After knowing which elements are in the system, we should define which 
fields there are in every one of them. The user should build his own DB in 
the proprietary files {conf.cpp & conf.h). It is recommended to add in the 
genConf.h enum with all the fields, so any other handler that call the 
proprietary API will be able to use this enum (Other handler does include 
the proprietary header but the generic header only, so any defines that will 
be done there will not be public) but it is not mandatory. 

Let assume we need to configure the CPU clock rate, the structure will 
look something like that: 
typedef enum 
{ 

evjboardjopujolockrate, 
ev_board_cpujast 
}e_boardj:pu; 
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Let assume we need to configure the FRAMER clock rate and psd, the 
structure will look something like that: 
typedef enum 
{ 

EVJNTERFACE_FRAMER_CLOCKRATE, 
EVJNTERFACE_FRAMER_PSD. 
EV_INTERFACE_FRAMER_LAST 
}EJNTERFACE_FRAMER; 

Let assume we need to configure the FPGA clock rate, the structure will 
look something like that: 
typedef enum 
{ 

EVjCOMPONENTJ'PGAJZLOCKRA TE, 
EV_COMPONENT_FPGA_LAST 
}EjCOMPONENTJ'PGA: 

In addition the user should build is DB in the proprietary file {conf.cpp): 

static CS_UINT8 cpuClockRate; 

static S_FPGA fpga[MAX_FPGA] ; 

static S^FRAMER Jramer[MAX_FRAMERS] ; 

5-3. Defining the user proprietary functions 

The actual type and validity check of each field is not known to the 
generic handler, so a set function should be supplied by the user. 
The proprietary set fiinction should be in the following structure: 
CSJNTS setFRAMER(CSJNT32* data, CSJJINT8 field, CSJJINTS element) 

The data will be a pointer to the value that is requested to set, the field will 
be which field to set (i.e. EV_INTERFACE_FRAMERJ:lOCKRATE) and 
element will be which element (i.e. 0, is the first framer). 
The fiinction should return RC_OK if the data was updated successfixUy 
otherwise RC_FAIL. 

A fiinction should be declared for each element in the system, in our 
example: 

setCPU 

setFRAMER 

setFPGA 

5.4. Connecting the data to the generic handler 

All we have lefl; is to connect the DB and the proprietary fiinction to the 
generic part. In conficpp there are skeleton fiinctions for: 

initBoardFunctions 
in itInterfaceFunctions 
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initComponentFunctions 

In order to connect the generic to the DB, an array of pointers to the actual 
field should be built. For example: 

void* framerParam Vector[h4AX_FRAMERS][EV_INTERFACEJ'RAMER_LAST]: 
CSJUINT8 i: 

for (i=0;i<MAX_FRAMER;i++) 
{ 

framerParamVector[i][EV_INTERFACE_FARMER_CLOCKRATE]= 

&framer[ ij. clockRate; 

framerParamVector[i][EVJNTERFACEJ^RAh4ERJ'SD]=&framer[i].psd^ 

} 

Now we should call the addlnterface to add our new interface into the 
system: 

addInterface(EVJNTERFACE_FRAMER,(void*)setFRAMER, 
(void**)framerParam VectonEVJNTERFA CE_FRAMER_LAST, MAX^FRAMER); 

Those calls are made for each element in board, interface and components 
categories. 

After the calls are made the access to the DB is via the API: 

To set framer 1 (remember it is zero base index) clock rate: 
CSJJINT32 framerClockRate-=^29: 

CONF_SetInterfaceElement(EVJNTERFACE_FRAMER, 

EVJNTERFACE_FRAMER_CLOCKRATE,iScframerClockRateJ): 

To get framer 0 clock rate; 

framerClockRate= *(CS_UINT32 *)(CONFJ}etInterfaceElement( 

EV_INTERFACE_FRAMER,EVJNTERFACE_FRAMERJCLOCKRATE.O)); 



5.5. Building the state machine 

The state machine need several steps: 

5.5.1. Defining the states 

The first step toward building the states machine is to define the 
states. In genConfh file there is a structure EJSTATES that hold all 
the states, add the required states there (you must keep the element 
EV_STATE_LAST at the end of the structure). 
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For example let assume we need three states shutdown, restart and 
show time. The structure should look like this: 



typedef enum 
{ 

EVJSTATEJSHUTDOWN, 
EV_STATE_RESTARZ 
EVJSTA TEJSHOWTIME, 
EVJSTATE_LAST 
JEJSTATES: 



5.5.2. Defining the actions 

In order to move between states, an event should happened. Those 
events called actions and should be defined in F ACTIONS 
structure (you must keep the element EV_ACTION_LAST at the end 
of the structure). 

For example let define the following events: 



typedef enum 
{ 

EV_A CTION_SHUTDOWN. 
EV_ACTION_START, 
EV_A CTION_RESTART, 
EV_A CTION_SES_HIGH, 
EV_ACTIONJLINK_DOWN, 
EV_ACTION_LINK_UP, 
EV_ACTION_LAST 
}E_ACTIONS; 



5.5.3. Defining the user proprietary functions 

Every state can have an entering and exiting function. The user 
should define the fimction according to the following prototype: 
void restartEnter(E_ACTIONS action) 
void restartExit(E_ACTIONS action) 

Where action will be the event that cause the transfer. 

5.5.4. Building the transfer matrix 

When the states and actions are known, we should define which 
event in any state transfer to which event. This should be done in 
the skeleton function fillStateMachine, 
For example: 

E_STATESmoveMatrix[EV_STATE_LAST][EV_ACTIONJAST]; 
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//Building the move matrix, could be built in a single const matrix. 

moveMatrix[EV_STATE_SHUTDOWN][EV_ACTION_SHUTDOWN]= 

EVJSTATEJSHUTDOWN; 

moveMatrix[EV_STA TE_SHUTDO WN][EV_ACTION_START] = 
EV_STA TE_RESTART: 

moveMatrix[E V_STA TE_SHUTDO WN][EV_ACTIONJiESTART]= 
EV_STA TERESTART; 

moveMatrix[EV_STATEJSHUTDOWN][EV_ACTION__SES_HIGH]=- 
EV_STA TE^SHUTDOWN; 

moveMatrix[EV_STATE_SHUTDOWN][EVjiCTION_LINKJ)OWN]= 
EVJSTA TEJSHUTDOWN; 

moveMatrixfEVJSTATEJSHUTDOWNJfEy_ACTIONJ.INK_UPJ= 
EVJSTATEJSHOfVTIME; 

moveMatrixfEV__STATE_RESTARTJfEV_ACTlONJSHUTDOlVNJ= 
E V^STA TE_SHUTD O WN; 

moveMatrix[EV_STATEJtESTART][EV_ACTIONJSTART]= 
EV_STATE_RESTART: 

moveMatrixfEVJSTATE_RESTARTJfEV_ACTION_RESTARTJ= 
EV_STATE_RESTART; 

moveMatrix[EV_STATEJiESTART][EV_ACTION_SES_HIGH]= 
EVJSTA TE_RESTART; 

moveMatrix[E V_STA TEJiESTART] [E V_A CT10N_LINK_D0 WN]= 
E V_STA TEJtESTAR T; 

moveMatrix[EV_STATE_RESTART][EV_ACTION_LlNK_UP]= 
EVJSTA TEJSHOWTIME: 

moveMatrix[EV_STATE_SHOWTIME][EV_ACTION_SHUTDOWN]^ 
EVJSTA TEJSHUTDOWN: 

moveMatrixfEVJSTA TE_SHOWTIME][EV_A CTION_START]=^ 
E V_STA TE_SHO WTIME; 

moveMatrixfEVJSTA TE_SHOWTIME] [EV_ACTIONJiESTART] 

^EV_STA TEJIESTART: 
moveMatrix[EV_STATE_SHOWTIME][EV_ACTION_SES_HIGH]= 
EVJSTA TEJiESTART: 

moveMatrix[EV_STATE_SHOWTIME][EV_ACTIONJINKj:>OWN]= 
EVJSTA TEJIESTART: 

moveMatrix[EV_STATEJHOWTlME][EVJiCT10NJlNKJJP]^ 
EV_STA TEJSHOWTIME: 

5.5.5. Connecting the data to the generic handler 

All the data is ready all we need it to connect it to the generic 
handler. This is done with the following function: 

setStateMachine(EVJSTATEJiEASTART(void*)restartEnter, 

(void*)restartExit,moveMatrix[EV_STATEJiESTART]): 

setStateMachine(EVJSTATEJSHUTDOWN,(voidVshutdownEnten 

NULL. moveMatrixfEVJSTATEJSHUTDOWNlCSJTRUE): 
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In the above case restart state was declared with both enter and exit 
functions. Shutdown state was declared with only enter function 
and it is the initial state. 

Now on any event all there is left to do is to send it via the API: 
CONF_SendAction(EV_ACTIONjSTART); 




5.6. Important issues 

For a reminder some important issues: 

1) The proprietary set function should return RC_OK if the update was 
successfiiUy completed otherwise RC_FAIL. 

2) When adding elemetss to the relevant structures, do not delete 
EV_BOARDJ.AST, EVJNTERFACEJASZ EVjCOMPONENT_LAST and 
leave them at the end of the list. 



6. Module Integration 

This module is only called by other modules, it does not have any special 
integration requirements. 
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1, Document Overview 

This document mainly contain two parts. One to describe the architecture and 
implementation of the generic maintenance handler. The second, a manual how to 
use the generic handler to build a proprietary maintenance handler. 
For a programmer that is itching to start his proprietary handler is recommended 
to read section 2 & 3 before jumping to section 5. Section 3 describe in more 
details the implementation of the generic handler. 

2, Module Overvievy 

This handler provides a mechanism for performing different maintenance 
requests. Those request can be done on power-up such as system self-test, can 
come from the NMS such as loopbacks, or periodically such as sanity test. These 
requests are performed on HW components, the drivers layer provides a HW API 
package in order to be able to perform those tests. The handler calls the 
corresponding API and returns the status of the component. 
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3, Module Architecture 

The module can be divided into two parts the generic one and the proprietary one. 





MIB Handler 






7 .-, ,.. ^ 



ApF^lcation Handler 



Generic Part 


/I N 


Proprietary 
Part 


SI 1/ 




The generic part will have a well defined API toward other handler, such as the 
MIB handler. And a self mechanism to do the generic work (such as periodic 
sanity test). The proprietary part will be written by the user and will do the actual 
calls to the HW & HW API. In the proprietary part the user will define all the 
hardware elements that will be maintained and will connect his fimctions to the 
generic part (see more details in section 4.3 & 5). The user will add all the HW 
component that can be tested, and will supply a function to do those tests. From 
this moment all the calls will be made through the generic handler APIs. 
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4. Module Implementation 

4.1. Control flow 

The handler have a main initialization function MArNT_Init, this function 
will initialize the internal handler database. After the initialization it 
require that the user will give for each HW component its test function, for 
the sanity check the user is require to give the interval between test and an 
alarm to trigger in case the test fails. 

After this initialization the test can be initiated by calling the API (see 
section 4.3 & 5). The sanity test will be done automatically and will 
trigger the relevant alarms if necessary. 

4.2. DB & Data structures 

The return value of the test functions are CS_INT8, a positive or zero 
value mean that the test was succeed. Negative value mean that the test 
failed, M_NOTCHECKED=-127 mean that the test did not perform. 

4.2.1. Data structures 



^LL^ /¥^r^;% K S SELFTESTrl " 




iMariible.type "^l-r:^ 4.. 'I 


;*feescriptibri..^, . d^S^^ 


PFunc 


Void* 


A pointer to the testing Unction. 


LastResult 


CS INT8 


The last result 




mili^ ^'c::: ' ^^fsXNitYXEST 


Variable name^ 


Vanable typefi:^^! % 


^Description ' :j 1 


PFunc 


Void* 


A pointer to the testing function. 


Timer 


CS_UINT16 


The interval between tests (in 
minutes) zero mean do not test. 


Counter 


CS UINT16 


Time passed from the last test 


Alarm 


CS_INT8 


The alarm number to trigger if 
the test fail. 


LastResult 


CS rNT8 


The last result 




^^^..r:^ - ' S GENERALFUNC?.^^^ ^ " ^ 


X^ariablelnamei. M 


^.Variableitype ,^ _.^'\^<. 


'Desci^iptidnt, V 


PFunc 


Void* 


A pointer to the testing function. 



4.2.2. Database 

There are three databases in the system: 

1 ) selfTest of S_SELFTEST records. 

2) sanityTest of S_S ANITYTEST records. 

3) generalFimc of S_GENERALFUNC records. 

The size of the databases depends on how many components are in 
each one. 
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4.3. API 

4.3.1. API to other handlers 

There are several APIs that enable other handler (especially the 
MIB handler) to communicate with the handler. 

Syntax: void MAINTJnitO 

This is the main initialization function. It should be called 
once on power-on. 

Syntax: CS_INT8 MAINT_SelfTestElment(E_SELFTEST element) 

This function get an HW component and run the test that 
connected to him. The return value is the return value of 
the test. Greater or equal to zero is success, negative value 
is failure. 

Syntax: CS_INT8 MAINT_SelJTestSysteinO 

This function run all the tests of the HW components. The 
return value is the number of element that failed the test. 
Zero all the components passed the test, other the number 
of component failed the test. 

Syntax: CS_INT8 MAINT_GetLastSelfTestResult(E_SELFTEST element) 
This function get an HW component and return the last test 
result of that component. (See MAINT_SelJTestElement for 
return values) 

Syntax: CSJNT8 MAIN_GetLastSamtyTestResult(E_SANITYTEST 

element) 

This function get an HW component that has a periodically 
sanity test, and retum the last test result. 

Syntax: CSJNT8 MAINT_CallFunc(E_GENERALFUNQvoid\void* 

void*,void* 
void*,coid*) 

This function get a general function name and her relevant 
parameters, it call the connected function and retum it 
retum value. 
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4.3.2, API between the generic and the proprietary parts 
Syntax: void setSelfTestElement(E_SELFTEST, void*) 

This function get and HW component and a pointer to it 
test function. The function update the self-test DB so when 
a self-test is requested to that component it will be 
connected to it test function. 



Syntax: voidsetSanityTestElement(EJSELFTEST, void*, CS_UINT16, 

CSJNTS) 

This function get and HW component, a pointer to it sanity 
test function, an interval for doing the test (the interval is in 
minutes) and an alarm number to be notify if the test fail. 
The function update the sanity-test DB so when a sanity- 
test is requested to that component it will be connected to it 
test function. 

Syntax: voidsetGeneralFuncElement(E_SELFTEST, void*) 

This function get a function symbol and a pointer to its 
function. The function update the generalFunc DB so when 
a call to a function is requested, it will be connected to it 
function. 



Syntax: void initSelJTestFunctionO 

In this function the user should put all his calls to 
setSelJTestElement. This function is called by MAINTJnit 
function on power-on. 

Syntax: void initSanityTestFunctionO 

In this function the user should put all his calls to 
setSanityTestElement. This function is called by 
MAINT_Imt function on power-on. 

Syntax: void initGeneralFuncFuncdonO 

In this function the user should put all his calls to 
setGeneralFuncElement. This function is called by 
MAINTJnit function on power-on. 

Syntax: void initProprietaryO 

In this function the user should put all his proprietary 
initializations. This function is called immediately after all 
the generic handler initializations are done by MAINT_Init 
function on power-on. 
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4.4. Detailed implementation 

The implementation of this handler is quite simple. We have a common 
header file between the generic and the proprietary section , in this header 
the user define all the HW components in his system (see detail 
explanation in section 5), On the generic section we have three databases: 
selfTest, sanityTest, generalFunc. In the proprietary source file 
(maint.cpp) we provide a skeleton functions for the user to fill. In those 
function the user suppose to connect his proprietary functions to the DB. 
We provide the user an API to fill the DB with a pointers to his 
proprietary functions (see section 5). We also provide a skeleton function 
for general purpose initialization that will be called on power-on, if the 
user need to do some initialization to his data, this is the place. On power- 
on all those skeleton functions will be called by MAINTJnit, this function 
will also release a task that will wake up every minute to check if there is 
a sanity check to perform, if there is the proprietary function of that 
specific sanity check will be called. If the sanity check failed and the 
alarm is not disabled then an alarm will be send (using the generic alarm 
handler). All other handler my perform test to HW components or call 
some general function using the well known API without knowing the real 
implementation of the user in the proprietary section. 




5. How to start 

In this section it will be described how take the generic handler and turn it into a 
working full maintenance handler. First we should divide the work into four 
stages: identifying the HW components, defining the self-test functions, defining 
the sanity-test functions and the other general functions. 

5.1. Identifying the HW components 

First we should take a look at our HW component and see which of them 
can be tested (for example on power-on) those will insert to the self-test 
category. Then we need to see which of tihem need a periodically checking 
those will insert into the sanity-test category (each component can be in 
more than one category). Those component who can perform more 
complex maintenance activity will put into the general function (for 
example checking the SNR on a link, or doing a loopback). 

5.2. Defining the self-test functions 

After knowing which component need self-test let the handler know about 
them too. In maint.h file there is a structure E_SELFTEST that hold all the 
components who need to be self-test, add it to there (you must keep the 
element EVJSELFTESTJLAST at the end of the structure). 
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For example let assume we have a transceiver and a FPGA in the system 
who need self-test. The structure should look like this: 



typedef enum 
{ 

EV_SELFTESTjrRANS, 
EV_SELFTEST_FPGA, 
EV_SELFTEST_LAST 
}E_SELFTEST; 



In the file maintcpp you should write the actual function that test the 
hardware. The return value must be zero or greater is the test succeeded, 
negative value if failed (-127 is reserved). 

For the above example let assume you wrote the following functions: 
testTransO 
testFPGAO 

Now you should tell the handler about those function. In the 
initSelfTestFunctions you should call setSelJTestElement for every HW 
element. In our example the function should look like this: 

void initSelfTestFunctions (void) 
{ 

setSel/TestElement(EVJSELFTESTjrRANS,(voidViestTRANS); 
setSelfTestElement(EVJSELFTEST_FPGA,(void*)testFPGA); 

} 

That is all! For example you can test your system by calling: 
MAINT_SelfrestSystem() 



5.3. Defining the sanity-test functions 

After knowing which component need periodically sanity-test let the 
handler know about them too. In maint.h file there is a structure 
EJSANITYTEST that hold all the components who need to be periodically 
tested, add it to there (you must keep the element EV_SANITYTEST_LAST 
at the end of the structure). 

For example let assume we have a FPGA that needs to be tested every 30 
minutes, if it fails it should send the EV__ALARM__FPGA. And a PHY that 
needs to be test every 10 minutes, if it fails it should send the 
EV_ALARM_PHY (The alarms should be declared in the alarm handler). 
The structure should look hke this: 



typedef enum 



Generic Maintenance handler Software Design for generic line card 
11 



Page 
Revision 




SYSTEMS 



{ 

EV_SANITYTEST_FPGA. 
EV_SANITYTEST_PHY, 
EV_SANITYTESTJ.AST 
}E_SANITYTEST; 



orrigent 



In the file maint.cpp you should write the actual function that test the 
hardware. The return value must be zero or greater is the test succeeded, 
negative value if failed (-127 is reserved). 

For the above example let assume you wrote the following functions: 
sanityTestFPGAO 
sanityTestPHYQ 

Now you should tell the handler about those function. In the 
initSanityTestFunctiom you should call setSanityTestElement for every HW 
element. In our example the function should look like this: 

void initSanityTestFunctions (void) 
{ 

setSamtyTestEiement(EVJSANITYTEST_FPGA,(void*)samtyTestFPGA, 

30,EV_ALARM_FPGA); 
setSamtyTestElement(EV_SANITYTEST_PHY, (void^sanityTestPHY, I ft 

EV_ALARMJPHY); 

} 

That is all! The handler will automatically perform the tests in the 
requested interval, and if it fails it will send the requested alarm. If there is 
a need to disable a test then you should call it with timeout 0. For example 
let disable the FPGA sanity test: 

setSanityTestElement(EV_SANITYTEST_FPGA, (voidVsamtyTestFPGA, ft 

EV_ALARM_FPGA); 



5.4. Defining the general functions 

After knowing what component need more complex function let the 
handler know about them too. In mainth file there is a structure 
E GENERALFUC that hold all the components who need more complex 
function, add it to there (you must keep the element EV_GEN_LAST at the 
end of the structure). 

For example let assume we need to do SNR check for a link, and do 
LOOPBACK to some link with loopBackType. 
The structure should look like this: 



typedef enum 

{ 
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EVj3EN_LOOPBA CK 
EV_GEN_SNRSCHEK 
EV_GENJ.AST 
}E_GENERALFUNC; 

In the file maintcpp you should write the actual function that do requested 
operation. The function must take 6 pointers as an arguments (if you do 
not need some of them leave them void*). For the above example let 
assume you wrote the following functions: 

CS_INT8 doLoopBackflnt"^ linkNumJnt* loopType.void^.void'^, void*, void*) 
{ 

printf ("Doing loop back to link %d, loop back type %d.\n'\ 

*linkNum, VoopType); 

return 1; 

) 

CSJNT8 checkSNR(int* linkNum,void* void* void* void* void*) 
{ 

printfCSNR on link %d, is 3db.W\ *linkNum); 
return 3; 

} 

Now you should tell the handler about those function. In the 
initOeneralFuncFunctions you should call setGeneralFuncElement for every 
function. In our example the function should look like this: 

void initGeneralFuncFunctions (void) 
{ 

setGeneralFuncElement(EVJjEN_LOOPBACK(void*)doLoopBack): 
setGeneralFuncElement(EV_GENJSNRCHECK(void*)checkSNR); 

} 

That is all! For example you can do loopback to link 3 loopType 5: 

int linkNum=3; 
int loopType=5; 

MAINTjCailFunc(EVJ}ENJ.OOPBACK iSclinkNum, &loopType); 
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5.5. Important issues 

For a reminder some important issues: 

1) The self-test and the sanity-test should return CS_INT8, where zero or 
greater indicates that the test succeeded, negative value indicates that 
the test failed, where -127 is a reserved number. 

2) When adding HW components to the relevant structures, do not delete 
EV_SELFTEST_LAST, EV_SANITYTEST_LAST, EV_GEN_LAST 
and leave them at the end of the list. 

3) The prototype of the general function must contain six pointers, you 
may not use them all, you may cast them to any other pointer, but you 
must have six pointers as an arguments. 



6. Module Integration 

This module integrate only with the alarm handler. In order to test the handler we 
need to get from the alarm handler all the relevant alarm numbers so we can call 
them if necessary. 
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1. Document Overview 

This document mainly contains two parts. One to describe the architecture and 
implementation of the generic alarm handler. The second, a manual how to use 
the generic handler to build a proprietary alarm handler. 

For a programmer that is itching to start his proprietary handler is recommended 
to read section 2 & 3 before jumping to section 5. Section 3 describes in more 
details the implementation of the generic handler. 

2. Module Overview 

This handler provides a mechanism for performing different alarm types the alarm 
handler is responsible to notify the NMS (usually by trap) of any critical event 
that occurred in the system. When an event occurs the handler should be 
activated. The communication is one way, The Alarm handler receives request 
from all the handlers in the system operate a certain function and sends the 
relevant trap to the NMS if necessary. 

The alarm handler is the only one at the system that responsible for reacting upon 
the different kind of alarm that flowing at the system including sending the trap. 
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3, Module Architecture 

The module can be divided into two parts the generic one and the proprietary one. 



MIB Handler 



1^ 



Application Handler 



Generic Part 



Proprietary 
Part 



HW API 




The generic part will have a well-defined API toward other handler, such as the 
MIB handler. And a self-mechanism to do the generic work (such as waiting on 
the mailbox for incoming alarm messages). The proprietary part will be written by 
the user and will do the actual calls to the alarm user handler function. In the 
proprietary part the user will define for each alarm type its handle fiinction, and 
will initilaize the priorities for each alarm at the system. (See section 4.3 & 5 for 
more details in). 

The user will add all the Alarm types definitions and their relative functions to 
operate at the case that any system alarm has been activated. 
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4. Module Implementation 
4.1. Control flow 




The handlers send a message to the Alarm mailbox, the Alarm handler read the 
messages one by one at the time it wake up (Or the Alarm handler will wake up 
upon incomming new alarm message - it can work in those two ways depends on 
configuration). And send each message to a specific routine. Each of those 
routines belongs to a specific handler - the handler which generate the alarm, and 
thus each of those routines operate different actions depends on the handlers 
sending the Alarm message. 

The alarm handler main initialization function - Alarmlnit, initialize the internal 
handler database. After the initialization it creates the alarm handler mailbox. And 
creates then the alarm task. 
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Alarm Handler data flow: 




Alarm handler 



Handler 



4.2. DB & Data structures 

The alarm handler maintain four different databases: 

• Alarm system status - This struct contain information about the status of 
the system alarms Active/Not Active, Reprted To NMS/Not Reprted To 
NMS. 

• Alarm system functions - This struct pass on to each alarm the relevant 
handler function to take care of this alarm. 

• Alarm System Enable - A Structure contain the Alarm state - 
enable/disable by the NMS, The default all the alarms are enable. 

• Alarm system Priorities - In that struct the alarm arrange by their Priority. 

4.2.1. Data structures 











realAlannStatus 


CS_UINT8 


Array contains information on the 
alarms current atatus. 


reportingAlarmStatus 


CS_UINT8 


Array contains information about 
reporting of alarms to the NMS. 










: Description -^^^ 


AlamiFunction 


Void* 


A pointer to the Alarm handle 
function. 




l»Sii^'%-;f>>^\-* S ALARM ACTIVE - ' 


->yariable,^namelS,* t . 


SVanaSllftypet^AS^xt^^^ 


iDe&cnption ^ - - 'J 


alarmEnable 


CS UINT8 


Alarms Enable/Disable. 
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AlarmPrioListEntry[MaxAlarmType] 
[MaxPrioEntry] 



CS UINT8 



Structer contain the system alarms 
and the alarms with higher priority 
at the same entry. 



4.2.2. Database 

There are four databases in the system: 

1) alarmState of S_ALARM_ST ATE records. 

2) LC^AlarmFunctionTable of S_ALARM_FUNCTION_TABLE 
records. 

3) alarmActiveStatus of S_ALARM_ACTIVE records. 

4) LC_AlarPrioTableof S_ALARM_PRIO_TABLE. 

The size of the databases depends on how many components are in 
each one. 

4.3. API 

4.3.1. API to other handlers 

There are several APIs that enable other handler (especially the 
MIB handler) to communicate with the Alarm handler. 



Syntax: void Alarmlnit (void) 

This is the main initialization function. It should be called 
once on power-on. 

Syntax: ini SendMsgToAlarmMBX (CS_UINT8 alarmNum, 

CS_UINT32 alarmParam = NULL) 
This function send alarm message to the alarm handler MBX. 

Syntax: void EnableSpecificAlarm (CS_ UINT8 alarmNum) 

The function Enable Specific Alarm. (Upon NMS request.) 

Syntax: void DisableSpecificAlarm (CSJUINT8 alarmNum) 

The function Disable Specific Alarm. (Upon NMS request.) 

Syntax: void EnableAUAlarms (void) 

The function Enable All the system Alarms. 

Syntax: void DisableAllAlarms (void) 

The function Disable All the system Alarms. 
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4.3.2. API between the generic and the proprietary parts 

Syntax: CS_UINT8 Is_AlarmEnable (CS_UINT8 alarmNum) 
The function Check whether the alarm is active or not. 

Syntax: CS_UINT8 CheckAlarmReportStatus (CS_UINT8 

alarmType), 

This function checks whether the alarm has been reported 
to the NMS. 

Syntax: CS_UINT8 CheckAlarmRealStatus (CS_UINT8 

alarmType) 

This function checks whether the alarm has already been 
activated. 

Syntax: CS_UINT8 Is^alarmTypeOn (CS_UINT8 

newAlarm Type) 

This function desides whether new incoming alarm is AlarmOff or 
AlarmOn. 

Syntax: CS_UINT8 SendTrapToNMS (CS__UINT8 

new A larm Type) 
This function send trap to the NMS on occasional alarm. 

Syntax: void AlarmPrioTablelnitialize (void) 

This function Initialize the Alarm Priority Table. 

Each entry of that table represents an Alarm type, and the user with 

system alarms is filling each entry with higer priority. 

Syntax: AlarmTypeFunctionlnitialize(void) 

In this function the user should refer to each alarm type a 
proprietary handle function. This function is called at the 
Alarmlnit when the entire generic handler is being initiahzed. 
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4.4. Detailed implementation 

The alarm handler would implement as a TASK with a high priority. 

The Alarm handler task will wake up upon a message that has been sent to, 

through the other handlers. 

When the Alarm handler wake up, the first thing it does: pulling up messages 
from the Alarm MailBox. Then the Alarm handler checked the following: 

• Is the Alarm Enable or Disable? 

• Is the Alarm message is Alarm Off or Alarm On? 
Then it operates the function Alarm WhatToDoNow. 

This function are operate the alarm algorithm, there the handler deside what to to 
do with the new incoming alarm message: updating databases, sending a Trap to 
the NMS through the MIB handler, or operate a specific Led - what ever required 
handling with the alarm message. 

Remark: Traps - the trap mechanism as it implemented in the MIB is change 

oriented. Its mean that when alarm is on the status field of this alarm is changed 

and a trap is generated, when this alarm is off the status is changed again and the 

same trap will be generated again now for clearing this alarm. 

The alarm handler will manage all the alarm in the system and will have a logic 

unit, which will have the ability to decide if to send the traps, or not. 

The alarm handler will be able to discard alarms messages neither coming from 

the handlers because another high priority alarm received and it causes to all the 

other alarms and there is no meaning to handle them nor sending traps. 

In order to implemnt that logic mechanism the Alarm handler maintain the 

following structure: 

#defme MAX_ALARM_TYPE 10 
struct AlarmState { 

unsigned char RealStatus[MAX_ALARM_TYPE]; 

unsigned char ReportingStatus[MAX_ALARM_TYPE]; 
}AlarmStatus; 

With that structure the Alarm handler can obtain which of the alarms have been 
activated and have been reported to the NMS and which of them have been 
activated and havn't been reported to the NMS. 

The alarm handler maintains a Priority Alarms DB initilaize by the user. 

typedef struct { 

CS_UINT8 

AlarmPrioListEntry[MAX_ALARM_TYPE][MAX_PRIORITY_ENTRY]; 
} S_AL ARM_PRIO_TABLE; 
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Each entry in that table represents a specific alarm type and a list of alarms with 
higher priority in the system. 
For instance: 



ALARM 


Higher 1 


Higher 2 


Higher 3 


Higher 4 


Higher 5 


TYPE 












1 


0 


0 


0 


0 


0 


5 


1 


2 


3 


4 


0 



The alarm algorithm Pseudo code: 

void AlarmMain (void) 
{ 

int status = CS_TRUE; 

S_ALARM_MESSAGE MsgAlarmBuf,*MsgAlarmBufP; 

MsgAlarmBufP = &MsgAlannBuf; 

while (status != ERROR) 
{ 

// Reading from the Msg Queue till there will be no message inside. 
// status = msgQReceive(AlarmQID, (char *)MsgAlarmBufP, 

MAX_ALARM_MSG_LEN, NO_WAIT); 

if (status != ERROR) 
{ 

if (Is_AlarmEnable(MsgAlarmBufP->alannType)) 

AlarmWhatToDoNow(MsgAlarmBufP->alarmType); 
else continue; 

} 

} 

} // End of AlarmMain 

static CS_UINT8 AlarmWhatToDoNow (CS_UINT8 newAlarmType) 
{ 

CS_UINT8 alarmOffOn; 
CS^UINTS alannlndex=l; 

alarmOffOn = Is_alarmTypeOn(newAlarmType); 

if(alarmOffOn) 

{ 

if (CheckAlarmRealStatus(newAlarmType)) 
return 0; 

alarmState.realAlarmStatus[newAlannType] = CS_ON; 

while (LC_AlannPrioTable. AlarmPrioListEntry [newAlarmType] [alarmlndex]) 
{ 

if 

(CheckAlarTnReaIStatus(LC_AlarmPrioTable.AlannPrioListEntry[newAlarmType][alarmIndex])) 
{ 

alarmlndex=l; 
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} 

else alarmlndex-H-; 

} 

alarmlndex=l; 

(*(P_FUNC_CAST)(LC_AlarniFunctionTableAlaimFunction[newAlannType]))(); 
alarmState.reportingAlarmStatus[newAlarmType] = CS_ON; 
SendTrapToNM S(newAlarmType) ; 
return 1; 

} 

else 
{ 

if ( ! (CheckAlarmRealS tatus(newAlannType- 1 ))) 
return 0; 

alarmState.realAlannStatus[newAlarmType-l] = CS_OFF; 
if (CheckAiarmReportStatus(newAlarmType- 1 )) 

{ 

alarmState.reportingAlarmStatus[newAlarmType-l] = CS__OFF; 
SendTrapToNMS(newAlarmType); 

} 

return 1; 

} 

} // End of AlarmWhatToDoNow 



5, How to start 



In this section it will be described how take the generic handler and turn it into a 

working full alarm handler. 

The user should implement the following items: 

• Definition of the system alarm type. 

• Initialization of the alarms priority table. 

• Initializations of the alarms handle function. 

• Rewrite the function that send trap to the SSM. 

1) The user should continue with list defined at the "AlarmType.h" and define 

the LC Internal Alarm. 
For instance: #define MAX_ALARM_TYPE 4 

#define MAINTENANCE__LOPPBACK_FAILED__ON 0x0001 
#define MAINTENANCE_LOPPBACK_F AILED _OFF 0x0002 
#define PM_UAS__ON 0x0003 
#defmePM UAS OFF 0x0004 
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2) The User shuld initilize the alarm priority table using the function: 
AlarmPrioTableUserlnitialize (void) inside this function the User should write 
into the Alarm Priority DB with the function setAlarmPriorityEntry 
(CS_INT8 alarmType, S_ALARM_PRIO_ENTRY alarmPrioList) the 
user can take the accsee to insert a whole entry to the DB. The function takes 
two parameters as an input: alarmTypeld and an array of five Bytes in which 
it defines the alarms, which have a higer priarity than the alarmTypeld. 

For instance the alarmTypeld = 3 

And the array is {4,5,0,0,0}. This means that the alarmTypeld 3 depends on 4 
& 5 and 4,5 are had a higer priority than alarmTypeld 3. 

3) The user should define a function to each alarm type that needed to be handle. 
In order to obtain a function to specific alarm type, it need to use the function: 
AlarmTypeFunctionUserlnitialize (void) there the user can update the Alarm 
Function DB using the function: void setAlarmFunction (CS_INT8 
alarmType, void* pFunc) which providing access to the Alarm 
Function DB. That function gets two parameters as input the alarmTypeld and 
the function that belongs to that alarm. 

In the file AlarmPrio.cpp the user should write the actual handle functions. 

4) The user should edit the function SendTrapToNMS (CS_UINT8 AlarmType) 
in accordance to the mechanism of SNMP sending Traps that depends on the 
agent MIB compiler code. 



6. Module Integration 

The handlers who engage with the Alarm handler are: 
Performance handler. 
Maintenance handler. 
MIB handler. 

In order to send a message to the alarm MBX the system handlers need to use the 
ALARM_MN_SendMsgToAlarmMBX API, which take as input the alarm type 
and the pgirameters if necessary. 



In order to send a trap to the MIB handler the alarm handler used the function 
SendTrapToNMS (CS_UINT8 AlarmType) 
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EXHIBIT E - CLEARCASE DOCUMENTATION VERSION CONTROL PRINTOUT 



M:\cc_vobs\pcc_qa\r&d\RTAIine_cards\doc\genericJc>deartool Ishis -fmt 

15.15-%"u %-8 .8Nd %n\ n" "pm handler pdr.doc " 

RAQUELB ■■■■ pm handler pdr.doc(§)@\main\2 

RAQUELB ^^^H pm handler pdr.doc@@\main\l 

RAQUELB ^^^^1 pm handler pdr.doc@@\ma(n\0 

RAQUELB ^^^^H pm handler pdr.doc@@\main 

RAQUELB ^^^^1 pm handler pdr.doc@@ 

M:\cc_vobs\pcc_qa\r&d\RT\line_cards\doc\genericJc>cleartool Ishis -fmt 
15.15-%"u %-8j8N^^\n" "generic configuration handler.doc " 
DAVIDR ^^^^B generic configuration handler.doc@@\main\2 
DAVIDR ^^^^1 generic configuration handler.doc@@\main\l 
DAVIDR ^^^^1 generic configuration handler.doc@@\main\0 
DAVIDR ^^^^H generic configuration handler.doc@@\main 
DAVIDR generic configuration handler.doc@@ 



IM:\cc_vobs\pcc 
15.15-%"U %-8 
RAQUELB 
RAQUELB 
RAQUELB 
RAQUELB 



^qa\r&d\RT\line_cards\doc\genericJc>cleartool Ishis -fmt 
.8Nd %n\ n" "generic maintenance handler.doc " 

generic maintenance handler.doc@@\main\l 
generic maintenance handler.doc@@\main\0 
generic maintenance handler.doc@@\main 
generic maintenance handler.doc@@ 




M :\cc_vobs\pcc_qa\r&d\RT\line_cards\doc\genericJc>cleartool Ishis 
15.15-%"u %-8j8Nd%n\n" "generic alarm handler.doc " 
RAQUELB HBHH generic alarm handler.doc@@\main\l 
RAQUELB ^^^^H generic alarm handler.doc@@\main\0 
RAQUELB ^^^^H generic alarm handler.doc@@\main 
RAQUELB HiHH generic alarm handler.doc@@ 



•fmt 
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